# Python Virtual Environment Usage

This document describes the basic Python virtual environment workflow on Quectel Pi M1/L1. A virtual environment isolates project dependencies and avoids changing the system Python environment.

## Environment Check

```bash
python3 --version
cat /etc/os-release
command -v pip3 || echo "pip3 not installed"
```

| **Item** | **Description** |
| --- | --- |
| OS | Currently verified as Debian GNU/Linux 13 (trixie) |
| Python | Currently verified as Python 3.13.5 |
| pip3 | Not detected by default on the current image; install it as needed |

## Create and Activate

```bash
sudo apt update
sudo apt install -y python3-venv python3-pip
mkdir -p ~/projects/python-demo
cd ~/projects/python-demo
python3 -m venv .venv
source .venv/bin/activate
```

## Manage Dependencies

```bash
python -m pip install --upgrade pip
pip install <package_name>
pip freeze > requirements.txt
pip install -r requirements.txt
```

For hardware-related Python projects, install required packages inside the virtual environment, for example:

```bash
pip install pyserial requests python-periphery
```

## Deactivate

```bash
deactivate
```

## Notes

- Do not commit the `.venv` directory to source control.

- Keep `requirements.txt` with the project for reproducible deployment.

- On Debian 13, avoid using `--break-system-packages` unless it is truly required.